

<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Output &mdash; CodeCarbon 3.1.1 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=03e43079" />
      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
      <script src="_static/documentation_options.js?v=796a81b5"></script>
      <script src="_static/doctools.js?v=9bcbadda"></script>
      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Collecting emissions to a logger" href="to_logger.html" />
    <link rel="prev" title="Advanced Installation" href="advanced_installation.html" /> 
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="index.html" class="icon icon-home">
            CodeCarbon
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <p class="caption" role="heading"><span class="caption-text">Introduction</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="motivation.html">Motivation</a></li>
<li class="toctree-l1"><a class="reference internal" href="methodology.html">Methodology</a></li>
<li class="toctree-l1"><a class="reference internal" href="rapl.html">RAPL Metrics</a></li>
<li class="toctree-l1"><a class="reference internal" href="model_examples.html">Model Comparisons</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Getting Started</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installing CodeCarbon</a></li>
<li class="toctree-l1"><a class="reference internal" href="usage.html">Quickstart</a></li>
<li class="toctree-l1"><a class="reference internal" href="usage.html#configuration">Configuration</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">CodeCarbon API</a></li>
<li class="toctree-l1"><a class="reference internal" href="parameters.html">Parameters</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="comet.html">Comet Integration</a></li>
<li class="toctree-l1"><a class="reference internal" href="advanced_installation.html">Advanced Installation</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Logging</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Output</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#csv">CSV</a></li>
<li class="toctree-l2"><a class="reference internal" href="#prometheus">Prometheus</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#using-codecarbon-with-prometheus">Using CodeCarbon with prometheus</a></li>
<li class="toctree-l3"><a class="reference internal" href="#how-to-test-in-local">How to test in local</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#logfire">Logfire</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#using-codecarbon-with-logfire">Using CodeCarbon with logfire</a></li>
<li class="toctree-l3"><a class="reference internal" href="#how-to-use-it">How to use it</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#http-output">HTTP Output</a></li>
<li class="toctree-l2"><a class="reference internal" href="#codecarbon-api">CodeCarbon API</a></li>
<li class="toctree-l2"><a class="reference internal" href="#logger-output">Logger Output</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="to_logger.html">Collecting emissions to a logger</a></li>
<li class="toctree-l1"><a class="reference internal" href="visualize.html">Visualize</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="index.html">CodeCarbon</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
      <li class="breadcrumb-item active">Output</li>
      <li class="wy-breadcrumbs-aside">
            <a href="_sources/output.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="output">
<span id="id1"></span><h1>Output<a class="headerlink" href="#output" title="Link to this heading"></a></h1>
<section id="csv">
<h2>CSV<a class="headerlink" href="#csv" title="Link to this heading"></a></h2>
<p>The package has an in-built logger that logs data into a CSV file named <code class="docutils literal notranslate"><span class="pre">emissions.csv</span></code> in the <code class="docutils literal notranslate"><span class="pre">output_dir</span></code>, provided as an
input parameter (defaults to the current directory), for each experiment tracked across projects.</p>
<table class="docutils align-center" id="id4">
<caption><span class="caption-text">Data Fields Logged for Each Experiment</span><a class="headerlink" href="#id4" title="Link to this table"></a></caption>
<colgroup>
<col style="width: 20.0%" />
<col style="width: 80.0%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Field</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>timestamp</p></td>
<td><p>Time of the experiment in <code class="docutils literal notranslate"><span class="pre">%Y-%m-%dT%H:%M:%S</span></code> format</p></td>
</tr>
<tr class="row-odd"><td><p>project_name</p></td>
<td><p>Name of the project, defaults to <code class="docutils literal notranslate"><span class="pre">codecarbon</span></code></p></td>
</tr>
<tr class="row-even"><td><p>run-id</p></td>
<td><p>id of the run</p></td>
</tr>
<tr class="row-odd"><td><p>duration</p></td>
<td><p>Duration of the compute, in seconds</p></td>
</tr>
<tr class="row-even"><td><p>emissions</p></td>
<td><p>Emissions as CO₂-equivalents [CO₂eq], in kg</p></td>
</tr>
<tr class="row-odd"><td><p>emissions_rate</p></td>
<td><p>emissions divided per duration, in Kg/s</p></td>
</tr>
<tr class="row-even"><td><p>cpu_power</p></td>
<td><p>CPU power (W)</p></td>
</tr>
<tr class="row-odd"><td><p>gpu_power</p></td>
<td><p>GPU power (W)</p></td>
</tr>
<tr class="row-even"><td><p>ram_power</p></td>
<td><p>RAM power (W)</p></td>
</tr>
<tr class="row-odd"><td><p>cpu_energy</p></td>
<td><p>Energy used per CPU (kWh)</p></td>
</tr>
<tr class="row-even"><td><p>gpu_energy</p></td>
<td><p>Energy used per GPU (kWh)</p></td>
</tr>
<tr class="row-odd"><td><p>ram_energy</p></td>
<td><p>Energy used per RAM (kWh)</p></td>
</tr>
<tr class="row-even"><td><p>energy_consumed</p></td>
<td><p>sum of cpu_energy, gpu_energy and ram_energy (kWh)</p></td>
</tr>
<tr class="row-odd"><td><p>country_name</p></td>
<td><p>Name of the country where the infrastructure is hosted</p></td>
</tr>
<tr class="row-even"><td><p>country_iso_code</p></td>
<td><p>3-letter alphabet ISO Code of the respective country</p></td>
</tr>
<tr class="row-odd"><td><p>region</p></td>
<td><p>Province/State/City where the compute infrastructure is hosted</p></td>
</tr>
<tr class="row-even"><td><p>on_cloud</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">Y</span></code> if the infrastructure is on cloud, <code class="docutils literal notranslate"><span class="pre">N</span></code> in case of private infrastructure</p></td>
</tr>
<tr class="row-odd"><td><p>cloud_provider</p></td>
<td><p>One of the 3 major cloud providers, <code class="docutils literal notranslate"><span class="pre">aws/azure/gcp</span></code></p></td>
</tr>
<tr class="row-even"><td><p>cloud_region</p></td>
<td><div class="line-block">
<div class="line">Geographical Region for respective cloud provider,</div>
<div class="line">examples <code class="docutils literal notranslate"><span class="pre">us-east-2</span> <span class="pre">for</span> <span class="pre">aws,</span> <span class="pre">brazilsouth</span> <span class="pre">for</span> <span class="pre">azure,</span> <span class="pre">asia-east1</span> <span class="pre">for</span> <span class="pre">gcp</span></code></div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>os</p></td>
<td><div class="line-block">
<div class="line">os on the device</div>
<div class="line">example <code class="docutils literal notranslate"><span class="pre">Windows-10-10.0.19044-SP0</span></code></div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>python_version</p></td>
<td><p>example <code class="docutils literal notranslate"><span class="pre">3.8.10</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>cpu_count:</p></td>
<td><p>number of CPU</p></td>
</tr>
<tr class="row-even"><td><p>cpu_model</p></td>
<td><p>example <code class="docutils literal notranslate"><span class="pre">Intel(R)</span> <span class="pre">Core(TM)</span> <span class="pre">i7-1065G7</span> <span class="pre">CPU</span> <span class="pre">&#64;</span> <span class="pre">1.30GHz</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>gpu_count</p></td>
<td><p>number of GPU</p></td>
</tr>
<tr class="row-even"><td><p>gpu_model</p></td>
<td><p>example <code class="docutils literal notranslate"><span class="pre">1</span> <span class="pre">x</span> <span class="pre">NVIDIA</span> <span class="pre">GeForce</span> <span class="pre">GTX</span> <span class="pre">1080</span> <span class="pre">Ti</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>longitude</p></td>
<td><div class="line-block">
<div class="line">Longitude, with reduced precision to a range of 11.1 km / 123 km².</div>
<div class="line">This is done for privacy protection.</div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>latitude</p></td>
<td><div class="line-block">
<div class="line">Latitude, with reduced precision to a range of 11.1 km / 123 km².</div>
<div class="line">This is done for privacy protection.</div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>ram_total_size</p></td>
<td><p>total RAM available (Go)</p></td>
</tr>
<tr class="row-even"><td><p>Tracking_mode:</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">machine</span></code> or <code class="docutils literal notranslate"><span class="pre">process``(default</span> <span class="pre">to</span> <span class="pre">``machine</span></code>)</p></td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Developers can enhance the Output interface, based on requirements. For example, to log into a database, by implementing a custom Class
that is a derived implementation of base class <code class="docutils literal notranslate"><span class="pre">BaseOutput</span></code> at <code class="docutils literal notranslate"><span class="pre">codecarbon/output.py</span></code></p>
</div>
</section>
<section id="prometheus">
<h2>Prometheus<a class="headerlink" href="#prometheus" title="Link to this heading"></a></h2>
<section id="using-codecarbon-with-prometheus">
<h3>Using CodeCarbon with prometheus<a class="headerlink" href="#using-codecarbon-with-prometheus" title="Link to this heading"></a></h3>
<p><a class="reference external" href="https://github.com/prometheus/prometheus">Prometheus</a> is a systems and service monitoring system. It collects metrics from configured targets at given intervals, evaluates rule expressions, displays the results, and can trigger alerts when specified conditions are observed.</p>
<p>CodeCarbon exposes all its metrics with the suffix <cite>codecarbon_</cite>.</p>
<p>Current version uses pushgateway mode. If your pushgateway server needs auth, set your environment values <cite>PROMETHEUS_USERNAME</cite> and <cite>PROMETHEUS_PASSWORD</cite> so codecarbon is able to push the metrics.</p>
</section>
<section id="how-to-test-in-local">
<h3>How to test in local<a class="headerlink" href="#how-to-test-in-local" title="Link to this heading"></a></h3>
<p>Deploy a local version of Prometheus + Prometheus Pushgateway</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>docker-compose<span class="w"> </span>up
</pre></div>
</div>
<p>Run your EmissionTracker as usual, but with the parameter <cite>save_to_prometheus</cite> as True.
e.g.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="o">...</span>
<span class="n">tracker</span> <span class="o">=</span> <span class="n">OfflineEmissionsTracker</span><span class="p">(</span>
            <span class="n">project_name</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">project_name</span><span class="p">,</span>
            <span class="n">country_iso_code</span><span class="o">=</span><span class="s2">&quot;USA&quot;</span><span class="p">,</span>
            <span class="n">save_to_prometheus</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
        <span class="p">)</span>
<span class="n">tracker</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
<span class="o">...</span>
</pre></div>
</div>
<p>Go to <a class="reference external" href="http://localhost:9090">localhost:9090</a>. Search for <cite>codecarbon_</cite>. You will see all the metrics there.</p>
</section>
</section>
<section id="logfire">
<h2>Logfire<a class="headerlink" href="#logfire" title="Link to this heading"></a></h2>
<section id="using-codecarbon-with-logfire">
<h3>Using CodeCarbon with logfire<a class="headerlink" href="#using-codecarbon-with-logfire" title="Link to this heading"></a></h3>
<p><a class="reference external" href="https://docs.pydantic.dev/logfire/">Logfire</a> is an observability platform.</p>
<p>CodeCarbon exposes all its metrics with the suffix <cite>codecarbon_</cite>.</p>
</section>
<section id="how-to-use-it">
<h3>How to use it<a class="headerlink" href="#how-to-use-it" title="Link to this heading"></a></h3>
<p>Run your EmissionTracker as usual, but with the parameter <cite>save_to_logfire</cite> as True.
e.g.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="o">...</span>
<span class="n">tracker</span> <span class="o">=</span> <span class="n">OfflineEmissionsTracker</span><span class="p">(</span>
            <span class="n">project_name</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">project_name</span><span class="p">,</span>
            <span class="n">country_iso_code</span><span class="o">=</span><span class="s2">&quot;USA&quot;</span><span class="p">,</span>
            <span class="n">save_to_logfire</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
        <span class="p">)</span>
<span class="n">tracker</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
<span class="o">...</span>
</pre></div>
</div>
<p>The first time it will ask to log in into Logfire. Once you log in and set the default logfire project, you are good to go, the metrics will appear following the format <cite>codecarbon_*</cite>.</p>
</section>
</section>
<section id="http-output">
<h2>HTTP Output<a class="headerlink" href="#http-output" title="Link to this heading"></a></h2>
<p>The HTTP Output allow the call of a webhook with emission data when the tracker is stopped.</p>
</section>
<section id="codecarbon-api">
<h2>CodeCarbon API<a class="headerlink" href="#codecarbon-api" title="Link to this heading"></a></h2>
<p>You can send all the data to the CodeCarbon API. So you have all your historical data in one place. By default, nothing is sent to the API.</p>
</section>
<section id="logger-output">
<h2>Logger Output<a class="headerlink" href="#logger-output" title="Link to this heading"></a></h2>
<p>See <a class="reference internal" href="to_logger.html#collecting-emissions-to-a-logger"><span class="std std-ref">Collecting emissions to a logger</span></a>.</p>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="advanced_installation.html" class="btn btn-neutral float-left" title="Advanced Installation" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="to_logger.html" class="btn btn-neutral float-right" title="Collecting emissions to a logger" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2020, BCG GAMMA, Comet.ml, Haverford College, MILA.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>